The NetworkDifferences-Aspect

Nadja Bramkamp genannt Beckmann1*

1University of Augsburg

*nadja.bramkampgenanntbeckmann@student.uni-augsburg.de

Contents

1 The NetworkDifferences-Aspect

The NetworkDifferences aspect allows the tracking and visualization of the differences of two RCX-objects. The first part of this vignette explains in detail how this aspect works and at the end we take a closer look at how this functionality can be used for a real-life example. Many biological entities like proteins and genes are represented as biological networks with nodes and edges and comparing these networks can help to answer questions in medical research e. g. the real-life example illustrates how the NetworkDifferences aspect can be used to visualize the differences regarding genes, gene expression and other aspects of two breast cancer patients.

The NetworkDifferences aspect website is available at https://github.com/frankkramer-lab/RCX-NetworkDifferences
The basis for this package is the RCX package by Florian Auer. The json-based datastructure CX is often used to store biological networks and the RCX package adapts the CX format to standard R data formats to create and modify, load, export, and visualize networks.

The NetworkDifferences aspect tracks the differences of two networks, represented as RCX-objects. First, two RCX-objects left and right are created that will be used as examples later.

left <- RCX::createRCX(
    nodes = RCX::createNodes(
        id = 0:2, name = c("A", "B", "C"),
        represents = c("r1", "r2", "r3")
    ),
    edges = RCX::createEdges(
        source = c(0, 1, 2),
        target = c(1, 2, 0),
        interaction = c("E1", "E2", "E3")
    ),
    nodeAttributes = RCX::createNodeAttributes(
        propertyOf = c(0, 1),
        name = rep("type", 2),
        value = list("w", c("x", "y"))
    ),
    edgeAttributes = RCX::createEdgeAttributes(
        propertyOf = c(0, 1),
        name = rep("type", 2),
        value = c("k", "l")
    ),
    networkAttributes = RCX::createNetworkAttributes(
        name = c("name", "author"),
        value = c("left network", "Donald Duck")
    )
)

right <- RCX::createRCX(
    nodes = RCX::createNodes(
        name = c("A", "B", "X"),
        represents = c("r1", "r4", "r5")
    ),
    edges = RCX::createEdges(
        source = c(0, 1, 2),
        target = c(1, 2, 0),
        interaction = c("E1", "E2", "E3")
    ),
    nodeAttributes = RCX::createNodeAttributes(
        propertyOf = c(0, 1),
        name = c("type", "type"),
        value = list("z", c("x", "y"))
    ),
    edgeAttributes = RCX::createEdgeAttributes(
        propertyOf = c(0, 1),
        name = rep("type", 2),
        value = list("n", c("l", "m"))
    ),
    networkAttributes = RCX::createNetworkAttributes(
        name = c("name", "description"),
        value = c("right network", "sample network")
    )
)

Now, we have two RCX-objects and with the compareNetworks-function we can track their differences. To illustrate the difference between matchByName set to TRUE respectively FALSE, we define two RCX-objects called rcxMatchByNameTRUE and rcxMatchByNameFALSE.

rcxMatchByNameTRUE <- compareNetworks(left, right, matchByName = TRUE)
rcxMatchByNameFALSE <- compareNetworks(left, right, matchByName = FALSE)

1.1 The compareNetworks-function

The compareNetworks-function is provided to track the differences regarding the nodes, nodeAttributes, edges, edgeAttributes, and networkAttributes and has three parameters: the two RCX-objects left, right, and the boolean matchByName. The names left and right are based on the join-operation. If matchByName is TRUE, two nodes are equal when their names are equal; if matchByName is FALSE, two nodes are equal when their represents are equal.

The function returns an RCX network whereby the nodes, nodeAttributes, edges, and edgeAttributes of the right network are appended to the corresponding aspects of the left network. The networkAttributes are ignored as it is not possible to append the networkAttributes of the right network to the networkAttributes of the left network if the networkAttributes have the same name. An additional aspect called the NetworkDifferences aspect is added to the RCX network. It is a list with the matchByName-boolean and five dataframes to track the differences of nodes, nodeAttributes, edges, edgeAttributes, and networkAttributes of the two RCX objects.

The structure of the returned RCX object is:

|---nodes: left nodes, right nodes
|---nodeAttributes: left nodeAttributes, right nodeAttributes
|---edges: left edges, right edges
|---edgeAttributes: left edgeAttributes, right edgeAttributes
|---networkDifferences
|   |---nodes: differences of the nodes
|   |   |---id
|   |   |---name / nameLeft
|   |   |---representLeft / nameRight
|   |   |---representRight / nameLeft
|   |   |---oldIdLeft
|   |   |---oldIdRight
|   |   |---belongsToLeft
|   |   |---belongsToRight
|   |---nodeAttributes: differences of the nodeAttributes
|   |   |---name
|   |   |---propertyOf
|   |   |---belongsToLeft
|   |   |---belongsToRight
|   |   |---dataTypeRight
|   |   |---dataTypeLeft
|   |   |---isListLeft
|   |   |---isListRight
|   |   |---valueLeft
|   |   |---valueRight
|   |---edges: differences of the edges
|   |   |---id
|   |   |---source
|   |   |---target
|   |   |---interaction
|   |   |---oldIdLeft
|   |   |---oldIdRight
|   |   |---belongsToLeft
|   |   |---belongsToRight
|   |---edgeAttributes: differences of the edgeAttributes
|   |   |---name
|   |   |---propertyOf
|   |   |---belongsToLeft
|   |   |---belongsToRight
|   |   |---dataTypeRight
|   |   |---dataTypeLeft
|   |   |---isListLeft
|   |   |---isListRight
|   |   |---valueLeft
|   |   |---valueRight
|   |---networkAttributes: differences of the networkAttributes
|   |   |---name
|   |   |---belongsToLeft
|   |   |---belongsToRight
|   |   |---dataTypeRight
|   |   |---dataTypeLeft
|   |   |---isListLeft
|   |   |---isListRight
|   |   |---valueLeft
|   |   |---valueRight

1.1.1 The combined RCX network

The combined network adds the aspects of the right network to the left network. For the nodes it is:

rcxMatchByNameTRUE$nodes

## Nodes:
##   id name represents oldId
## 1  0    A         r1     0
## 2  1    B         r2     1
## 3  2    C         r3     2
## 4  3    A         r1     0
## 5  4    B         r4     1
## 6  5    X         r5     2

The dataframe for the nodeAttributes has updated values for propertyOf for the nodeAttributes of the right network.

rcxMatchByNameTRUE$nodeAttributes

## Node attributes:
##   propertyOf name value dataType isList
## 1          0 type     w   string  FALSE
## 2          1 type  x, y   string   TRUE
## 3          3 type     z   string  FALSE
## 4          4 type  x, y   string   TRUE

The dataframe for the edges contains updated values for source and target for the edges of the right network.

rcxMatchByNameTRUE$edges

## Edges:
##   id source target interaction oldId
## 1  0      0      1          E1     0
## 2  1      1      2          E2     1
## 3  2      2      0          E3     2
## 4  3      3      4          E1     0
## 5  4      4      5          E2     1
## 6  5      5      3          E3     2

The last aspect are the edgeAttributes, again with updated values for propertyOf for the edgeAttributes of the right network.

rcxMatchByNameTRUE$edgeAttributes

## Edge attributes:
##   propertyOf name value dataType isList
## 1          0 type     k   string  FALSE
## 2          1 type     l   string  FALSE
## 3          3 type     n   string  FALSE
## 4          4 type  l, m   string   TRUE

1.1.2 The networkDifferences-aspect

The NetworkDifferences-aspect contains the information regarding the differences of the nodes, nodeAttributes, edges, edgeAttributes, and networkÀttributes.

The nodes-dataframe

The nodes-dataframe tracks the differences of the nodes in eight columns. The names of the columns depend on the matchByName-boolean. If matchByName is TRUE the names of the columns are: id, name, representLeft, representRight, oldIdLeft, oldIdRight, belongsToLeft, and belongsToRight. If matchByName is FALSE the names of the columns are: id, name, representLeft, representRight, oldIdLeft, oldIdRight, belongsToLeft, and belongsToRight.

Example: The left network has three nodes called A, B, and C with the represents r1, r2, and r3.

left$nodes

## Nodes:
##   id name represents
## 1  0    A         r1
## 2  1    B         r2
## 3  2    C         r3

The right network has three nodes called A, B, and X with the represents r1, r4, and r5.

right$nodes

## Nodes:
##   id name represents
## 1  0    A         r1
## 2  1    B         r4
## 3  2    X         r5

If matchByName is TRUE, the created nodes-dataframe is:

rcxMatchByNameTRUE$networkDifferences$nodes

##   id name representLeft representRight oldIdLeft oldIdRight belongsToLeft
## 1  0    A            r1             r1         0          0          TRUE
## 2  1    B            r2             r4         1          1          TRUE
## 3  2    C            r3           <NA>         2       <NA>          TRUE
## 4  3    X          <NA>             r5      <NA>          2         FALSE
##   belongsToRight
## 1           TRUE
## 2           TRUE
## 3          FALSE
## 4           TRUE

If matchByName is FALSE, the created nodes-dataframe is:

rcxMatchByNameFALSE$networkDifferences$nodes

##   id nameLeft nameRight represent oldIdLeft oldIdRight belongsToLeft
## 1  0        A         A        r1         0          0          TRUE
## 2  1        B      <NA>        r2         1       <NA>          TRUE
## 3  2        C      <NA>        r3         2       <NA>          TRUE
## 4  3     <NA>         B        r4      <NA>          1         FALSE
## 5  4     <NA>         X        r5      <NA>          2         FALSE
##   belongsToRight
## 1           TRUE
## 2          FALSE
## 3          FALSE
## 4           TRUE
## 5           TRUE

The nodeAttributes-dataframe

The nodeAttributes-dataframes tracks the differences of the nodeAttributes in ten columns. The names of the columns are: propertyOf, name, belongsToLeft, belongsToRight, dataTypeLeft, dataTypeRight, isListLeft, isListRight, valueLeft, and valueRight. Two nodeAttributes are equal if their names are equal and if they belong to the same node (defined through propertyOf).

Example: The nodes from section 1.2.1 have nodeAttributes: In both RCX-objects, the nodes with the id 0 and 1 have the attribute ‘type’.

left$nodeAttributes

## Node attributes:
##   propertyOf name value dataType isList
## 1          0 type     w   string  FALSE
## 2          1 type  x, y   string   TRUE

right$nodeAttributes

## Node attributes:
##   propertyOf name value dataType isList
## 1          0 type     z   string  FALSE
## 2          1 type  x, y   string   TRUE

If matchByName is TRUE, the nodeAttributes-dataframe is:

rcxMatchByNameTRUE$networkDifferences$nodeAttributes

##   propertyOf name belongsToLeft belongsToRight dataTypeLeft dataTypeRight
## 1          0 type          TRUE           TRUE       string        string
## 2          1 type          TRUE           TRUE       string        string
##   isListLeft isListRight   valueLeft  valueRight
## 1      FALSE       FALSE           w           z
## 2       TRUE        TRUE c("x", "y") c("x", "y")

If matchByName is FALSE, the nodeAttributes-dataframe is:

rcxMatchByNameFALSE$networkDifferences$nodeAttributes

##   propertyOf name belongsToLeft belongsToRight dataTypeLeft dataTypeRight
## 1          0 type          TRUE           TRUE       string        string
## 2          1 type          TRUE          FALSE       string          <NA>
## 3          3 type         FALSE           TRUE         <NA>        string
##   isListLeft isListRight   valueLeft  valueRight
## 1      FALSE       FALSE           w           z
## 2       TRUE        <NA> c("x", "y")        <NA>
## 3       <NA>        TRUE        <NA> c("x", "y")

The edge-dataframe

The edges-dataframe tracks the differences of the edges in eight columns. The names of the columns are: id, source, target, interaction, oldIdLeft, oldIdRight, belongsToLeft, and belongsToRight. Two edges are equal if their source and target are equal (the edges are undirected so the source and target can be switched) and if the interaction is equal or NA in both cases.

Example: Both RCX-objects from section 1.2.1 and 1.2.2 have three edges which have the interactions ‘E1’, ‘E2’, and ‘E3’.

left$edges

## Edges:
##   id source target interaction
## 1  0      0      1          E1
## 2  1      1      2          E2
## 3  2      2      0          E3

right$edges

## Edges:
##   id source target interaction
## 1  0      0      1          E1
## 2  1      1      2          E2
## 3  2      2      0          E3

If matchByName is set to TRUE, the edges-dataframe is:

rcxMatchByNameTRUE$networkDifferences$edges

##   id source target interaction oldIdLeft oldIdRight belongsToLeft
## 1  0      0      1          E1         0          0          TRUE
## 2  1      1      2          E2         1       <NA>          TRUE
## 3  2      2      0          E3         2       <NA>          TRUE
## 4  3      1      3          E2      <NA>          1         FALSE
## 5  4      3      0          E3      <NA>          2         FALSE
##   belongsToRight
## 1           TRUE
## 2          FALSE
## 3          FALSE
## 4           TRUE
## 5           TRUE

If matchByName is set to FALSE, the edges-dataframe is:

rcxMatchByNameFALSE$networkDifferences$edges

##   id source target interaction oldIdLeft oldIdRight belongsToLeft
## 1  0      0      1          E1         0       <NA>          TRUE
## 2  1      1      2          E2         1       <NA>          TRUE
## 3  2      2      0          E3         2       <NA>          TRUE
## 4  3      0      3          E1      <NA>          0         FALSE
## 5  4      3      4          E2      <NA>          1         FALSE
## 6  5      4      0          E3      <NA>          2         FALSE
##   belongsToRight
## 1          FALSE
## 2          FALSE
## 3          FALSE
## 4           TRUE
## 5           TRUE
## 6           TRUE

The edgeAttributes-dataframe

The edgeAttributes-dataframe tracks the differences of the edgeAttributes in ten columns. The names of the columns are: propertyOf, name, belongsToLeft, belongsToRight, dataTypeLeft, dataTypeRight, isListLeft, isListRight, valueLeft and valueRight. Two edgeAttributes are equal if their names are equal and if they belong to the same edge (defined through propertyOf).

Example: The edges from section 1.2.3 have edgeAttributes: In both RCX-objects, the edges with the id 0 and 1 have the attribute ‘type’.

left$edgeAttributes

## Edge attributes:
##   propertyOf name value dataType isList
## 1          0 type     k   string  FALSE
## 2          1 type     l   string  FALSE

right$edgeAttributes

## Edge attributes:
##   propertyOf name value dataType isList
## 1          0 type     n   string  FALSE
## 2          1 type  l, m   string   TRUE

If matchByName is TRUE, the edgeAttributes-dataframe is:

rcxMatchByNameTRUE$networkDifferences$edgeAttributes

##   propertyOf name belongsToLeft belongsToRight dataTypeLeft dataTypeRight
## 1          0 type          TRUE           TRUE       string        string
## 2          1 type          TRUE          FALSE       string          <NA>
## 3          3 type         FALSE           TRUE         <NA>        string
##   isListLeft isListRight valueLeft  valueRight
## 1      FALSE       FALSE         k           n
## 2      FALSE        <NA>         l        <NA>
## 3       <NA>        TRUE      <NA> c("l", "m")

If matchByName is FALSE, the edgeAttributes-dataframe is:

rcxMatchByNameFALSE$networkDifferences$edgeAttributes

##   propertyOf name belongsToLeft belongsToRight dataTypeLeft dataTypeRight
## 1          0 type          TRUE          FALSE       string          <NA>
## 2          1 type          TRUE          FALSE       string          <NA>
## 3          3 type         FALSE           TRUE         <NA>        string
## 4          4 type         FALSE           TRUE         <NA>        string
##   isListLeft isListRight valueLeft  valueRight
## 1      FALSE        <NA>         k        <NA>
## 2      FALSE        <NA>         l        <NA>
## 3       <NA>       FALSE      <NA>           n
## 4       <NA>        TRUE      <NA> c("l", "m")

The networkAttributes-dataframe

The networkAttributes-dataframes tracks the differences of the networkAttributes in nine columns. The names of the columns are: name, belongsToLeft, belongsToRight, dataTypeLeft, dataTypeRight, isListLeft, isListRight, valueLeft, and valueRight. Two networkAttributes are equal if their names are equal.

Example: The left and right RCX-objects have networkAttributes: the left RCX-object has a name ‘left network’ and an author ‘Donald Duck’.

left$networkAttributes

## Network attributes:
##     name        value dataType isList
## 1   name left network   string  FALSE
## 2 author  Donald Duck   string  FALSE

The right RCX-object has a name, too, ‘right network’ and a description ‘sample network’.

right$networkAttributes

## Network attributes:
##          name          value dataType isList
## 1        name  right network   string  FALSE
## 2 description sample network   string  FALSE

The networkAttributes-dataframe is:

rcxMatchByNameTRUE$networkDifferences$networkAttributes

##          name belongsToLeft belongsToRight dataTypeLeft dataTypeRight
## 1        name          TRUE           TRUE       string        string
## 2      author          TRUE          FALSE       string          <NA>
## 3 description         FALSE           TRUE         <NA>        string
##   isListLeft isListRight    valueLeft     valueRight
## 1      FALSE       FALSE left network  right network
## 2      FALSE        <NA>  Donald Duck           <NA>
## 3       <NA>        TRUE         <NA> sample network

1.2 The JSON-Conversion

The aspect can be converted to JSON and back in order to share the object. For the conversion to JSON the rcxToJSON-function is provided and returns a string of the json-conversion.

json <- toCX(rcxMatchByNameTRUE, verbose = TRUE)

## Processing standard aspects: RCX$metaData:
## Convert meta-data to JSON...done!
## Processing standard aspects: RCX$nodes:
## Convert nodes to JSON...done!
## Processing standard aspects: RCX$edges:
## Convert edges to JSON...done!
## Processing standard aspects: RCX$nodeAttributes:
## Convert node attributes to JSON...done!
## Processing standard aspects: RCX$edgeAttributes:
## Convert edge attributes to JSON...done!
## Processing non-standard aspects: RCX$networkDifferences:
## Convert NetworkDifferences to JSON...done!
## Done with RCX!

json

## [{"numberVerification":[{"longNumber":2147483647}]},{"metaData":[{"name":"nodes","version":"1.0","idCounter":5,"elementCount":6,"consistencyGroup":1},{"name":"edges","version":"1.0","idCounter":5,"elementCount":6,"consistencyGroup":1},{"name":"nodeAttributes","version":"1.0","elementCount":4,"consistencyGroup":1},{"name":"edgeAttributes","version":"1.0","elementCount":4,"consistencyGroup":1}]},{"nodes":[{"@id":0,"n":"A","r":"r1","oldId":0},{"@id":1,"n":"B","r":"r2","oldId":1},{"@id":2,"n":"C","r":"r3","oldId":2},{"@id":3,"n":"A","r":"r1","oldId":0},{"@id":4,"n":"B","r":"r4","oldId":1},{"@id":5,"n":"X","r":"r5","oldId":2}]},{"edges":[{"@id":0,"s":0,"t":1,"i":"E1","oldId":0},{"@id":1,"s":1,"t":2,"i":"E2","oldId":1},{"@id":2,"s":2,"t":0,"i":"E3","oldId":2},{"@id":3,"s":3,"t":4,"i":"E1","oldId":0},{"@id":4,"s":4,"t":5,"i":"E2","oldId":1},{"@id":5,"s":5,"t":3,"i":"E3","oldId":2}]},{"nodeAttributes":[{"po":0,"n":"type","v":"w","d":"string"},{"po":1,"n":"type","v":["x","y"],"d":"list_of_string"},{"po":3,"n":"type","v":"z","d":"string"},{"po":4,"n":"type","v":["x","y"],"d":"list_of_string"}]},{"edgeAttributes":[{"po":0,"n":"type","v":"k","d":"string"},{"po":1,"n":"type","v":"l","d":"string"},{"po":3,"n":"type","v":"n","d":"string"},{"po":4,"n":"type","v":["l","m"],"d":"list_of_string"}]},{"NetworkDifferencesAspect":[{"matchByName":"true"},{"nodes":[{"@id":"0","n":"A","rl":"r1","rr":"r1","oil":"0","oir":"0","btl":"TRUE","btr":"TRUE"},{"@id":"1","n":"B","rl":"r2","rr":"r4","oil":"1","oir":"1","btl":"TRUE","btr":"TRUE"},{"@id":"2","n":"C","rl":"r3","oil":"2","btl":"TRUE","btr":"FALSE"},{"@id":"3","n":"X","rr":"r5","oir":"2","btl":"FALSE","btr":"TRUE"}]},{"nodeAttributes":[{"po":"0","n":"type","btl":"TRUE","btr":"TRUE","dtl":"string","dtr":"string","ill":"FALSE","ilr":"FALSE","vl":"w","vr":"z"},{"po":"1","n":"type","btl":"TRUE","btr":"TRUE","dtl":"string","dtr":"string","ill":"TRUE","ilr":"TRUE","vl":"c(\"x\", \"y\")","vr":"c(\"x\", \"y\")"}]},{"edges":[{"@id":"0","s":"0","t":"1","i":"E1","oil":"0","oir":"0","btl":"TRUE","btr":"TRUE"},{"@id":"1","s":"1","t":"2","i":"E2","oil":"1","btl":"TRUE","btr":"FALSE"},{"@id":"2","s":"2","t":"0","i":"E3","oil":"2","btl":"TRUE","btr":"FALSE"},{"@id":"3","s":"1","t":"3","i":"E2","oir":"1","btl":"FALSE","btr":"TRUE"},{"@id":"4","s":"3","t":"0","i":"E3","oir":"2","btl":"FALSE","btr":"TRUE"}]},{"edgeAttributes":[{"po":"0","n":"type","btl":"TRUE","btr":"TRUE","dtl":"string","dtr":"string","ill":"FALSE","ilr":"FALSE","vl":"k","vr":"n"},{"po":"1","n":"type","btl":"TRUE","btr":"FALSE","dtl":"string","ill":"FALSE","vl":"l"},{"po":"3","n":"type","btl":"FALSE","btr":"TRUE","dtr":"string","ilr":"TRUE","vr":"c(\"l\", \"m\")"}]},{"networkAttributes":[{"n":"name","btl":"TRUE","btr":"TRUE","dtl":"string","dtr":"string","ill":"FALSE","ilr":"FALSE","vl":"left network","vr":"right network"},{"n":"author","btl":"TRUE","btr":"FALSE","dtl":"string","ill":"FALSE","vl":"Donald Duck"},{"n":"description","btl":"FALSE","btr":"TRUE","dtr":"string","ilr":"TRUE","vr":"sample network"}]}]},{"status":[{"error":"","success":true}]}]

The reconversion is the responsibility of the function jsonToRCX. The json-string has to be parsed and this parsed string can be reconverted to an RCX object with a NetworkDifferences aspect. This RCX object is printed and is identical to the original RCX object.

jsonParsed <- RCX:::parseJSON(json)
rcx <- RCX:::processCX(jsonParsed, verbose = TRUE)

## Parsing nodes...create aspect...done!
## Create RCX from parsed nodes...done!
## Parsing edges...create aspect...done!
## Add aspect "edges" to RCX...done!
## Parsing node attributes...create aspect...done!
## Add aspect "nodeAttributes" to RCX...done!
## Parsing edge attributes...create aspect...done!
## Add aspect "edgeAttributes" to RCX...done!
## Parsing meta-data...done!
## Ignore "numberVerification" aspect, not necessary in RCX!
## Can't process aspect "numberVerification", so skip it...done!
## Parsing networkDifferences...create aspect...done!
## Add aspect "NetworkDifferencesAspect" to RCX...done!
## Ignore "status" aspect, not necessary in RCX!
## Can't process aspect "status", so skip it...done!

rcx

## [[metaData]] = Meta-data:
##             name version idCounter elementCount consistencyGroup
## 1          nodes     1.0         5            6                1
## 2          edges     1.0         5            6                1
## 3 nodeAttributes     1.0        NA            4                1
## 4 edgeAttributes     1.0        NA            4                1
## 
## [[nodes]] = Nodes:
##   id name represents
## 1  0    A         r1
## 2  1    B         r2
## 3  2    C         r3
## 4  3    A         r1
## 5  4    B         r4
## 6  5    X         r5
## 
## [[edges]] = Edges:
##   id source target interaction
## 1  0      0      1          E1
## 2  1      1      2          E2
## 3  2      2      0          E3
## 4  3      3      4          E1
## 5  4      4      5          E2
## 6  5      5      3          E3
## 
## [[nodeAttributes]] = Node attributes:
##   propertyOf name value dataType isList
## 1          0 type     w   string  FALSE
## 2          1 type  x, y   string   TRUE
## 3          3 type     z   string  FALSE
## 4          4 type  x, y   string   TRUE
## 
## [[edgeAttributes]] = Edge attributes:
##   propertyOf name value dataType isList
## 1          0 type     k   string  FALSE
## 2          1 type     l   string  FALSE
## 3          3 type     n   string  FALSE
## 4          4 type  l, m   string   TRUE

1.3 The Conversion to RCX-objects

The NetworkDifferences aspect can be converted to RCX-objects in order to visualize the differences of the two RCX-objects left and right. There are three options: node-centered, edge-centered and a combined version. The user can decide if the names and the values of the node- or edgeAttributes should be included. The networkAttributes are not visualized as they are not considered to be important.

The elements that exist in both RCX-objects are colored gray, the elements that exist only in the left RCX-object are colored light blue and the elements that exist only in the right RCX-object are orange. The shapes for the nodes are:

RCX Element	Shape
node names	round
node represents	triangle
edge	rectangle
nodeAttributes name	hexagon
nodeAttribute value	parallelogram
edgeAttribute name	rectangle with round corners
edgeAttribute value	diamond

1.3.1 Node-centered RCX-objects

With the node-centered RCX-objects the user can visualize the differences of the two given RCX-objects regarding the nodes and, if wished, the names and values of the nodeAttributes. The exportDifferencesToNodeNetwork-function has the includeNamesAndRepresents-parameter; if this parameter is set to FALSE, either the represents or the names are visualized (depending on matchByName); if includeNamesAndRepresents is set to TRUE, both names and represents are visualized.

The position of the circles can be changed with several parameters:

• startLayerBoth has the default value 5 and determines the position at which the circles for the nodes that belong to both RCX-objects start

• startLayerLeftRight has the default value 10 and determines the position at which the circles for the nodes that belong only to one RCX-objects start (it must be greater than startLayerLeftRight)

• startLayerAttributes has the default value 0 and if this parameter is greater than startLayerLeftRight, it determines the position at which the circles for the names of the nodeAttributes start

• startLayerValues has the default value 0 and if this parameter is greater than startLayerAttributes, it determines the position at which the circles for the values of the nodeAttributes start

The following figure shows the the differences of the RCX-objects from the section 1.2 with matchByName is set to TRUE.

nodeNetwork <- exportDifferencesToNodeNetwork(
    rcxMatchByNameTRUE$networkDifferences, includeNamesAndRepresents = FALSE,
    startLayerBoth = 1, startLayerLeftRight = 2, startLayerAttributes = 3,
    startLayerValues = 4
)
visualize(nodeNetwork)

The next figure shows the result if matchByName is set to FALSE.

nodeNetwork <- exportDifferencesToNodeNetwork(
    rcxMatchByNameFALSE$networkDifferences, includeNamesAndRepresents = FALSE,
    startLayerBoth = 1, startLayerLeftRight = 2, startLayerAttributes = 3,
    startLayerValues = 4
)
visualize(nodeNetwork)

The last figure shows the results if matchByName and includeNamesAndRepresentsare TRUE.

nodeNetwork <- exportDifferencesToNodeNetwork(
    rcxMatchByNameTRUE$networkDifferences, includeNamesAndRepresents = TRUE,
    startLayerBoth = 1, startLayerLeftRight = 2, startLayerAttributes = 3,
    startLayerValues = 4
)
visualize(nodeNetwork)

Node-centered RCX-object with matchByName TRUE and includeNamesAndRepresents TRUE

1.3.2 Edge-centered RCX-objects

With the edge-centered RCX-objects the user can visualize the differences of the two given RCX-objects regarding the edges and, if wished, the names and values of the edgeAttributes. Like before, there are parameters startLayerBoth, startLayerLeftRight, startLayerAttributes, and startLayerValues to define the position of the nodes representing the edges and the names and values of the edgeAttributes (for more details see section 2.1).

The following figure shows the edge-centered RCX-object if matchByName is TRUE.

edgeNetwork <- exportDifferencesToEdgeNetwork(
    rcxMatchByNameTRUE$networkDifferences, startLayerBoth = 1,
    startLayerLeftRight = 2, startLayerAttributes = 3, startLayerValues = 4
)
visualize(edgeNetwork)

The next figure shows the result if matchByName is FALSE.

edgeNetwork <- exportDifferencesToEdgeNetwork(
    rcxMatchByNameFALSE$networkDifferences, startLayerBoth = 1,
    startLayerLeftRight = 2, startLayerAttributes = 3, startLayerValues = 4
)
visualize(edgeNetwork)

### Node- and edge-centered RCX-objects The last option are the creation of RCX-Objects that show the differences regarding the nodes, the edges, and the node- and edgeAttributes. The parameters are the same as for the node-centered option (section 2.1).

The following figure shows the node- and edge-centered RCX-object for the RCX-objects from section 1 with node- and edgeAttributes (matchByName is TRUE).

nodeEdgeNetwork <- exportDifferencesToNodeEdgeNetwork(
    rcxMatchByNameTRUE$networkDifferences, startLayerBoth = 1,
    startLayerLeftRight = 2, startLayerAttributes = 3, startLayerValues = 4
)
visualize(nodeEdgeNetwork)

The last figure shows the RCX-objects but without the node- and edgeAttributes.

nodeEdgeNetwork <- exportDifferencesToNodeEdgeNetwork(
    rcxMatchByNameTRUE$networkDifferences, startLayerBoth = 1,
    startLayerLeftRight = 2, startLayerAttributes = 0, startLayerValues = 0
)
visualize(nodeEdgeNetwork)

Node- and edge-centered RCX-object with matchByName TRUE without the visualization of the node- and edgeAttributes

2 Real-life example

The example from section 2 illustrates how the differences of the two RCX-objects are tracked. This section shows how this can be applied to a real life example: the visualization of the differences of two RCX objects representing two breast cancer patients. The two RCX-objects can be extracted from the “Combined patient-specific breast cancer subnetworks” (UUID a420aaee-4be9-11ec-b3be-0ac135e8bacf on NDEx) and they show the networks of two breast cancer patients. These networks have nodes that represent genes, edges between the nodes, and nodeAttributes for the gene expression, gene expression level, and relevance score whereby the patient id is part of the name of the nodeAttributes. On the basis of the names of the nodeAttributes the corresponding nodes and then the edges can be extracted. At the end, the patient ids are removed from the name of the nodeAttributes. The patient with the ID GSM615195 and the patient with the ID GSM615184 are selected for this example whereby the patient GSM615195 has developed metastasis within the first five years after the cancer diagnosis and patient GSM615184 remained metastasis-free. Visualizing the differences of two patients can help to determine the reasons for the metastasis-development.

library(stringr)

rcx = readCX("/home/n/Augsburg/Bachelorarbeit/Combined patient-specific breast cancer subnetworks.cx")

getNetwork <- function(
        patientID = NULL,
        rcx = NULL,
        filterNodeAttributes = ""
) {
    nodes <- rcx$nodes
    edges <- rcx$edges
    nodeAttributes <- rcx$nodeAttributes[startsWith(rcx$nodeAttributes$name, patientID),]
    nodeID <- c()
    for (i in 1:nrow(nodeAttributes)) {
        row = nodeAttributes[i,]
        if (startsWith(row$name, patientID)) {
            propID = row$propertyOf
            if (!(propID %in% nodeID)) {
                nodeID = append(nodeID, propID)
            }
        }
    }
    nodes = subset(nodes, id %in% nodeID)
    nodeAttributes <- subset(nodeAttributes, propertyOf %in% nodeID)
    for (i in 1:nrow(nodeAttributes)) {
        nodeAttributes[i,]$name <- str_remove(nodeAttributes[i,]$name, paste(patientID, "_", sep = ""))
    }
    if (nchar(filterNodeAttributes) > 0) {
        nodeAttributes <- nodeAttributes[nodeAttributes$name == filterNodeAttributes,]
    }
    edgeID <- c()
    for (i in 1:nrow(rcx$edges)) {
        row = rcx$edges[i,]
        if (row$source %in% nodeID && row$target %in% nodeID) {
            edgeID = append(edgeID, row$id)
        }
    }
    edges = subset(edges, id %in% edgeID)
    rcx = createRCX(nodes = nodes, edges = edges)
    rcx = updateNodeAttributes(rcx, nodeAttributes)
    return(rcx)
}

rcxGSM615195 <- getNetwork("GSM615195", rcx)

rcxGSM615184 <- getNetwork("GSM615184", rcx)

First, extractions for the nodes, nodeAttributes, and edges for the patient GSM615195 are shown.

head(rcxGSM615195$nodes)

## Nodes:
##   id   name
## 1  0  RPL41
## 2  1 EEF1A1
## 3  2   TPT1
## 4  4    UBC
## 5  6   ACTB
## 6  7  HUWE1

head(rcxGSM615195$nodeAttributes)

## Node attributes:
##   propertyOf  name        value dataType isList
## 1          0 Score    4.7819E-4   double  FALSE
## 2          1 Score  8.080652E-4   double  FALSE
## 3          2 Score 4.3818814E-4   double  FALSE
## 4          4 Score  5.548634E-4   double  FALSE
## 5          6 Score 7.1166584E-4   double  FALSE
## 6          7 Score 4.0993214E-4   double  FALSE

head(rcxGSM615195$edges)

## Edges:
##   id source target
## 1  0      0    414
## 2  1      1      2
## 3  2      1      6
## 4  3      1     16
## 5  4      1    179
## 6  6      1    268

Now, some extraction for the nodes, nodeAttributes, and edges for the patient GSM615184 are shown.

head(rcxGSM615184$nodes)

## Nodes:
##   id   name
## 1  0  RPL41
## 2  1 EEF1A1
## 3  2   TPT1
## 4  4    UBC
## 5  6   ACTB
## 6  7  HUWE1

head(rcxGSM615184$nodeAttributes)

## Node attributes:
##     propertyOf  name        value dataType isList
## 113          0 Score  5.119976E-4   double  FALSE
## 114          1 Score  9.223439E-4   double  FALSE
## 115          2 Score 4.4765728E-4   double  FALSE
## 116          4 Score  5.606382E-4   double  FALSE
## 117          6 Score  6.787086E-4   double  FALSE
## 118          7 Score  3.956429E-4   double  FALSE

head(rcxGSM615184$edges)

## Edges:
##   id source target
## 1  0      0    414
## 2  1      1      2
## 3  2      1      6
## 4  3      1     16
## 5  4      1    179
## 6  6      1    268

Now the visualization of the differences of the two RCX-objects regarding the nodes is created.

netDif <- compareNetworks(rcxGSM615195, rcxGSM615184, TRUE)

nodesNetwork <- exportDifferencesToNodeNetwork(netDif$networkDifferences)

visualize(nodesNetwork)

We can see that about half of the genes that are shown in these networks exist in both networks. These differences might be the reasons for the differences in the development of metastasis. Next, we include the names and the values of the nodeAttributes and see a detailed visualization of the differences of the two RCX-objects.

# nodesAttributesValuesNetwork =
# exportDifferencesToNodeNetwork(netDif$networkDifferences,
# startLayerAttributes = 15, startLayerValues = 20)

# visualize(nodesAttributesValuesNetwork)

This detailed visualization shows the differences of the nodeAttributes and their values. Taking a closer look at their differences can lead to more information about the difference metastasis-development.

3 Session info

sessionInfo()

## R version 4.2.2 Patched (2022-11-10 r83330)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Linux Mint 20.3
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.9.0
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.9.0
## 
## locale:
##  [1] LC_CTYPE=de_DE.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=de_DE.UTF-8        LC_COLLATE=de_DE.UTF-8    
##  [5] LC_MONETARY=de_DE.UTF-8    LC_MESSAGES=de_DE.UTF-8   
##  [7] LC_PAPER=de_DE.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=de_DE.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] stringr_1.5.0    RCX_1.1.0        BiocStyle_2.26.0
## 
## loaded via a namespace (and not attached):
##  [1] Rcpp_1.0.9          rstudioapi_0.14     knitr_1.41         
##  [4] magrittr_2.0.3      R6_2.5.1            rlang_1.0.6        
##  [7] fastmap_1.1.0       plyr_1.8.8          tools_4.2.2        
## [10] xfun_0.36           cli_3.5.0           jquerylib_0.1.4    
## [13] htmltools_0.5.4     yaml_2.3.6          digest_0.6.31      
## [16] lifecycle_1.0.3     bookdown_0.31       formatR_1.13       
## [19] BiocManager_1.30.19 sass_0.4.4          vctrs_0.5.1        
## [22] glue_1.6.2          cachem_1.0.6        evaluate_0.19      
## [25] rmarkdown_2.19      stringi_1.7.8       compiler_4.2.2     
## [28] bslib_0.4.2         jsonlite_1.8.4